<span class='headerItem'>CustJsonRPCDataSource Quick Introduction&nbsp;&nbsp;</span><p>
<a href="http://www.smartclient.com/">SmartClient</a> is a wonderful Ajax framework.<br>
Chances are that at some point SmartClient will provide a Json-RPC compatible data source out of the box. Until then you can use this one.<p>

If you are working on the SmartClient code feel free to reuse ours. We would love seeing a Json-RPC data source in SmartClient. Please have a look at the License section below.<p>

<h5>Purpose:</h5>
Use the CustJsonRPCDataSource class to connect your data aware SmartClient controls to a Json-RPC back end. It can be obtained from <a href="http://code.google.com/p/custjsonrpcdatasource-for-smartclient/">http://code.google.com/p/custjsonrpcdatasource-for-smartclient</a>

<h5>Warning:</h5>
If you did not so far you might want to make sure you understand how
<a href="http://getahead.org/blog/joe/2007/01/01/csrf_attacks_or_how_to_avoid_exposing_your_gmail_contacts.html">CSRF attacks</a> and
<a href="http://www.fortify.com/servlet/downloads/public/JavaScript_Hijacking.pdf">JavaScript hijacking</a> work before you use any Json-RPC mechanisms to talk to your back end!<br>
SmartClient supports mechanisms to avoid such attacks but you have to use them.<p>

Just a short example: Assume you do not implement any such mechanisms and your desktop and server are in an ultra secure area where only you have access. But you can receive email and click on a link like this one:
<a href="http://your_json_rpc_sever/rpc/admin?jsonrpc=2.0&method=dump_all_database_tables&id=1">Receive your long awaited sarlary raise.</a>

You got the point...


<h5>Usage:</h5>
First you need to include the data source class somewhere. Typically at the same place as ISC_Core.js:

<pre><code>
    &lt;SCRIPT SRC=CustJsonRPCDataSource.js&gt;&lt;/SCRIPT&gt;
</code></pre>

CustJsonRPCDataSource works pretty similar to SmartClient's RestDataSource.

Next define your data source:<p>

<pre><code>
    isc.CustJsonRPCDataSource.create({
        ID: &quot;countryListDS&quot;,
        // Currently there is a bug in SmartClient which means that if your
        // back end responses with http status codes != 200 in case of a server
        // error, SmartClient will run into problems when dataFormat = &quot;json&quot;
        // is used. As a work around you can use dataFormat = &quot;custom&quot;.
        // But as soon as this bug is fixed you should use dataFormat = &quot;json&quot;!
        //
        // Notice: If your back end responds with http status code = 200 for
        // server errors you should already use dataFormat = &quot;json&quot;.
        //
        // Also notice: Errors on application level (validation error, etc.)
        // should be sent back as successful JsonRPC call. See for the respective
        // examples!
        
        dataFormat: &quot;custom&quot;,
        //dataFormat: &quot;json&quot;,                     // use this as soon as bug is fixed.
        fields: [
            {name: &quot;countryCode&quot;, title: &quot;Country Code&quot;, primaryKey: true, canEdit: false},
            {name: &quot;government&quot;, title: &quot;Government&quot;},
            {name: &quot;capital&quot;, title: &quot;Capital&quot;},
            {name: &quot;population&quot;, title: &quot;Population&quot;},
            {name: &quot;independence&quot;, title: &quot;Independence&quot;}
        ],
        operationBindings : [
            // You should specify at least all four parameters operationType, 
            //   dataURL, serverMethod and dataProtocol!
            // dataURL points to your service. serverMethod specifies the
            // respective method of your service. dataProtocol should be
            // &quot;postMessage&quot; for a http POST or &quot;getParams&quot; for a http GET.
            // No other dataProtocols are currently supported.
            
            { operationType:&quot;fetch&quot;, dataURL:&quot;/rpc/countries/&quot;, serverMethod:&quot;query_country&quot;, dataProtocol:&quot;postMessage&quot;}
            { operationType:&quot;add&quot;, dataURL:&quot;/rpc/countries/&quot;, serverMethod:&quot;add_country&quot;, dataProtocol:&quot;postMessage&quot;}
            { operationType:&quot;update&quot;, dataURL:&quot;/rpc/countries/&quot;, serverMethod:&quot;update_country&quot;, dataProtocol:&quot;postMessage&quot;}
            { operationType:&quot;remove&quot;, dataURL:&quot;/rpc/countries/&quot;, serverMethod:&quot;remove_country&quot;, dataProtocol:&quot;postMessage&quot;}
        ]
    });
</code></pre>

Use this data source exactly as you would normally do with other data sources.

<h5>Examples:</h5>
Please have a look at the examples folder!

<h5>Error handling:</h5>
Please have a look at the examples folder!

<h5>Status:</h5>
All code here is alpha code! Do not use it in production if you are unsure. This code lacks of serious tests. E.g. dataProtocol = getParams will probably not work at all since I never tested it. My back end does not support http GET, yet. <p>


Currently CustJsonRPCDataSource should support Json-RPC 2.0 draft as specified under
<a href="http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal">JSON-RPC 2.0 Draft</a> and implements Json-RPC over http as specified here: <a href="http://groups.google.com/group/json-rpc/web/json-rpc-over-http">JSON-RPC over http</a>.<br>

Please notice that version 2.0 is only a draft at the moment.

So far CustJsonRPCDataSource does not support Json-RPC 1.0. Also many Json-RPC back ends are written especially to support a specific ajax framework. And since no Json-RPC specificaiton explained every aspect of a RPC mechanism, implementations might differ at some point. You might run into some problems.
Nevertheless it should not be a big issue to change this class in order to work together with your back end.<p>


<h5>Help wanted:</h5>
If you want to improve this code just drop by at <a href="http://code.google.com/p/custjsonrpcdatasource-for-smartclient/">http://code.google.com/p/custjsonrpcdatasource-for-smartclient</a>.

<h5>License:</h5>
Our Code first is licensed under the <a href="http://www.gnu.org/licenses/lgpl-3.0.html">LGPL</a>. That is the same license as SmartClient's LGPL license version. Of course you can use Our Code in your commercial projects without being forced to put your project under the LGPL.<p>

The only reason for Our Code's main license not being the New BSD License is that it reuses code from SmartClient. My understanding is that under those conditions Isomorpic Software Inc. would not be able to include Our Code in their commercially licensed SmartClient package. Not good. Therefore, if you are the entity who owns the rights of SmartClient and can issue other licenses to SmartClient's code (I guess this is Isomorpic Software Inc.) you are entitled to use Our Code under the following conditions:  
<pre>
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
I am not a lawyer. But I hope this makes everything clear. The intention is to not being made liable for this code but on the other side SmartClient's code owner should be able to reuse Our Code.<p>

<b>Attention</b>: CustJsonRPCDataSource also includes code from other authors which use different licenses. I belive that combining those licenses will not cause any incompatibilities. But as always as soon as we are touching law you should check for yourself.<p>

In detail CustJsonRPCDataSource contains:<p>

* Small portions of SmartClient code sometimes not marked in any special way.<p>

* The original json2.js from <a href="http://www.JSON.org/json2.js">http://www.JSON.org/json2.js</a>. The code was put into public domain. It is marked in CustJsonRPCDataSource.js.<p>

* The base64 functionality is adapted code from the Tibco GI 3.5.1 project. The original source was <a href="http://gi.tibco.com/svnweb/gi/view/trunk/gi/JSX/js/jsx3/util/package.js?rev=552">http://gi.tibco.com/svnweb/gi/view/trunk/gi/JSX/js/jsx3/util/package.js?rev=552</a>. It is marked in CustJsonRPCDataSource.js.<br>

Tibco GI's code uses the "BSD License": 

<pre>
-------------------------------------------------------------------------------
TIBCO General Interface(TM) - Professional Edition - BSD License

Copyright (c) 2001-2007, TIBCO Software Inc.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
--Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.
--Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.
--The name of TIBCO Software Inc. may not be used to endorse or
  promote products derived from this software without specific prior
  written permission of TIBCO Software Inc.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-------------------------------------------------------------------------------
</pre>
